/*
 * Copyright 2002-2019 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.beans.factory.config;

import org.springframework.beans.BeansException;
import org.springframework.lang.Nullable;

/**
 * 工厂钩子，允许自定义修改新的 Bean 实例 — 例如，检查标记接口或使用代理包装 bean。
 *
 * <p>通常，通过标记接口等填充 bean 的后处理器将实现 {@link postProcessBeforeInitialization}，
 * 而使用代理包装 bean 的后处理器通常会实现 {@link postProcessAfterInitialization}。
 *
 * <h3>注册</h3>
 * <p>{@code ApplicationContext} 可以在其 Bean 定义中自动检测 {@code BeanPostProcessor} bean，
 * 并将这些后处理器应用于随后创建的任何 bean。
 * 普通 {@code BeanFactory} 允许以编程方式注册后处理器，将它们应用于通过 Bean Factory 创建的所有 bean。
 *
 * <h3>订购</h3>
 * <p>在 {@code ApplicationContext} 中自动检测的 {@code BeanPostProcessor} 豆将根据
 * {@link org.springframework.core.PriorityOrdered} 和 {@link org.springframework.core.Ordered} 语义进行排序。
 * 相比之下，以编程方式向 {@code BeanFactory} 注册的 {@code BeanPostProcessor} bean 将按注册顺序应用;
 * 对于以编程方式注册的后处理器，将忽略通过实现 {@code PriorityOrdered} 或 {@code Ordered} 接口表示的任何排序语义。
 * 此外，{@link org.springframework.core.annotation.Order @Order} 注释不考虑 {@code BeanPostProcessor} bean。
 *
 * @author Juergen Hoeller
 * @author Sam Brannen
 * @since 10.10.2003
 * @see InstantiationAwareBeanPostProcessor
 * @see DestructionAwareBeanPostProcessor
 * @see ConfigurableBeanFactory#addBeanPostProcessor
 * @see BeanFactoryPostProcessor
 */
public interface BeanPostProcessor {

	/**
	 * 在任何 <i><i> Bean 初始化回调（如 InitializingBean 的 {@code afterPropertiesSet} 或自定义 init-method）之前，
	 * 将此 {@code BeanPostProcessor} 应用于给定的新 Bean 实例。
	 * Bean 已经填充了属性值。返回的 Bean 实例可能是原始实例的包装器。
	 *
	 * <p>默认实现按原样返回给定的 {@code bean}。
	 *
	 * @param bean the new bean instance
	 * @param beanName the name of the bean
	 * @return the bean instance to use, either the original or a wrapped one;
	 * if {@code null}, no subsequent BeanPostProcessors will be invoked
	 * @throws org.springframework.beans.BeansException in case of errors
	 * @see org.springframework.beans.factory.InitializingBean#afterPropertiesSet
	 */
	@Nullable
	default Object postProcessBeforeInitialization(Object bean, String beanName) throws BeansException {
		return bean;
	}

	/**
	 * 在任何 <i><i> Bean 初始化回调（如 InitializingBean 的 {@code afterPropertiesSet}
	 * 或自定义 init-method）之后，将此 {@code BeanPostProcessor} 应用于给定的新 Bean 实例。
	 * Bean 已经填充了属性值。返回的 Bean 实例可能是原始实例的包装器。
	 *
	 * 对于 FactoryBean<p>，将为 FactoryBean 实例和 FactoryBean 创建的对象（从 Spring 2.0 开始）调用此回调。
	 * 后处理器可以通过相应的 {@code Bean 实例 FactoryBean} 检查来决定是应用于 FactoryBean 还是创建的对象，还是同时应用于两者。
	 *
	 * <p>与所有其他 {@code BeanPostProcessor} 方法触发短路后，
	 * 此回调也将在 {@link InstanceiationAwareBeanPostProcessorpostProcessBeforeInstantiation} 方法触发短路后调用。
	 *
	 * <p>默认实现按原样返回给定的 {@code bean}。
	 *
	 * @param bean the new bean instance
	 * @param beanName the name of the bean
	 * @return the bean instance to use, either the original or a wrapped one;
	 * if {@code null}, no subsequent BeanPostProcessors will be invoked
	 * @throws org.springframework.beans.BeansException in case of errors
	 * @see org.springframework.beans.factory.InitializingBean#afterPropertiesSet
	 * @see org.springframework.beans.factory.FactoryBean
	 */
	@Nullable
	default Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
		return bean;
	}

}
